1994-1996 by Oberon microsystems, Inc., Switzerland.
All rights reserved. No part of this publication may be reproduced in any form or by any means, without prior written permission by Oberon microsystems. The only exception is the free electronic distribution of the education version of Oberon/F (see the accompanying
copyright
notice
for details).
Oberon/F module interfaces and their descriptions in particular may not be used in other works without written permission.
Oberon microsystems, Inc.
Technoparkstrasse 1
CH-8005 Z
Switzerland
Oberon is a trademark of ETH Z
rich, Switzerland.
Oberon/F, Oberon/L, "Oberon by Example", "The Oberon Tribune", "Oberon Developer Forum", and "Drag & Pick" are trademarks of Oberon microsystems, Inc.
All other trademarks and registered trademarks belong to their respective owners.
Helvetica
Helvetica
StdLinks.ShowTarget('Overview')
Helvetica
StdLinks.ShowTarget('Conventions')
StdLinks.ShowTarget('Installation Windows')
StdLinks.ShowTarget('Installation Mac OS')
StdLinks.ShowTarget('Installation Release')
StdLinks.ShowTarget('Deinstallation')
StdLinks.ShowTarget('Windows')
StdLinks.ShowTarget('Document Size')
StdLinks.ShowTarget('Menu Configuration')
StdLinks.ShowTarget('String Resources')
StdCmds.OpenBrowser('Text/Docu/Guide', 'User Guide for Text Subsystem')
StdCmds.OpenBrowser('Form/Docu/Guide', 'User Guide for Form Subsystem')
StdCmds.OpenBrowser('Dev/Docu/Guide', 'User Guide for Dev Subsystem')
StdLinks.ShowTarget('Standard Commands')
StdLinks.ShowTarget('File Menu')
StdLinks.ShowTarget('Edit Menu')
StdLinks.ShowTarget('Font Menu')
StdLinks.ShowTarget('Attributes Menu')
StdLinks.ShowTarget('Window Menu')
StdCmds.OpenBrowser('Std/Map', 'Map to the Standard Commands')
This document serves as a user's guide for Oberon/F programmers. It is not intended as a manual for the end user of software written in Oberon/F. Knowledge of the underlying platform's user interface guidelines is assumed.
With Oberon/F, there are no separate environments for developing programs, for testing and debugging programs, or for the distribution of programs. Instead there is only one, truly integrated, environment for all these purposes. A distribution version of an Oberon application is created simply by stripping away all tools which are specific to the development process.
Neither development tools nor documentation may be distributed. However, all other parts of Oberon/F may be freely distributed along with applications, without royalties or other fees.
Such a customized Oberon/F environment always has the basic capabilities of Oberon/F's compound document architecture, and of the standard text and form subsystems. Furthermore, it constitutes a standard Windows or Mac OS application, where the (boot) application can be double-clicked, where documents can be dropped onto the application icon to open them, etc.
"Native" applications which are only developed under, but not based on, Oberon/F can be developed as well. For this purpose, a linker tool is provided (only in the full version of the software, not in the education version). Normally, Oberon modules are linked and loaded dynamically, such that a separate linker is not strictly necessary. However, it is possible even for pure Oberon/F applications to link all or some of their modules together, in order to reduce the number of files to distribute. For further information about this topic, refer to the document
Platform-Specific
Issues
On-line documentation:
Text stretches which are blue and underlined are hyperlinks, and can be followed by clicking on them.
When working in the Oberon/F environment for the first time, the following may be helpful to remember: almost all modifications to Oberon/F documents are undoable, making it quite safe to try out a feature. In general, multi
level undo/redo is available, i.e. not only one, but several commands can be undone; as many as memory permits.
Mac OS:
Whenever the system is working on the completion of some command for more than a fraction of a second, Oberon/F changes the cursor to a special busy cursor sequence, i.e. a cursor which changes its shape as long as the command is running. However, this does not guarantee that the executing program does make any progress. For example, the busy cursor will keep advancing, even if the program entered an endless loop. Use command-option-. to terminate such a program. Note that it may take a few seconds before you see a reaction.
Windows:
On Windows NT and Windows 95, an endless loop can be terminated with ctrl-break.
Conventions
The contents of this documentation mostly applies to both the Windows and Mac OS versions of Oberon/F. Where there are differences, e.g. a feature only available on one platform, this is clearly indicated, e.g. as in the previous paragraph. In order to reduce the number of such platform-specific remarks, a few notational conventions are followed:
- Mac OS folders are called (sub)directories.
- Path names contain "/" as directory separators, as in Unix and in the World-Wide Web.
- File and directory names contain both capital and small letters.
- In chapters which are not Windows-specific, document file names are given without the ".odc" suffix used in Windows. Thus the file name Text/Rsrc/Find under Windows corresponds to Text\Rsrc\find.odc, and to Text:Rsrc:find under Mac OS.
- modifier key: on Windows this is the ctrl key, on Mac OS this is the option key.
- menu commands: M->I is a shorthand notation for menu item I in menu M, e.g. File->New.
- Differences between Windows and Mac OS may be denoted in three different ways: large differences are handled by giving two different sections, one for each platform. In this case, the sectin title ends in "(Windows only)" or "(Mac OS only)". If not indicated otherwise, the next section will apply to both platforms again. Smaller differences are described as short notes, typically there is a note on Windows-specific behavior, followed by a note on Mac OS-specific behavior. There is an example at the end of the previous section. For small differences, both versions are given in the same sentence, e.g. "To drag & pick, hold down the alt key (Windows) / command key (Mac OS) while dragging."
Installation (Windows only)
Start Setup.exe on disk number 1. The setup program will lead you through the installation procedure.
Oberon/F requires a PC with an i386 or better, with Windows 3.1, Windows for Workgroups, Windows NT 3.5, or Windows 95.
The resulting Oberon directory contains several files and directories:
Files:
OberonF.exe The Oberon/F boot application.
ReadMe.txt Release notes and copyright notice.
Tour.odc A quick tour through Oberon/F.
Directories:
Dev This directory contains the development subsystem.
Form This directory contains the Form subsystem with the visual designer.
Host This directory contains private code of Oberon/F.
Manuals This directory contains on-line documentation not specific to a particular
module or subsystem.
Obx This directory contains the Obx subsystem, a collection of examples.
Std This directory contains a number of command packages available to the user.
System This directory contains the core of Oberon/F.
Text This directory contains the Text subsystem, with the standard
document/program editor.
Installation (Mac OS only)
Start the Oberon
installer application on disk number 1. The installer will lead you through the installation procedure.
Oberon/F requires a Macintosh with a MC68020 or better, with Mac OS 7.0 or higher, and a floating point unit (FPU) or FPU emulator. If you don't have an FPU please read the Read
Me (FPU) file in the Oberon directory.
The resulting Oberon directory contains several files and directories:
Files:
OberonF The Oberon/F boot application.
Read Me Release notes and copyright notice.
Read Me (FPU) Information about a third-party floating-point emulator.
Tour A quick tour through Oberon/F.
Directories:
Dev This directory contains the development subsystem.
Form This directory contains the Form subsystem with the visual designer.
Host This directory contains private code of Oberon/F.
Mac This directory contains interface modules for direct Toolbox and Mac OS
access.
Manuals This directory contains on-line documentation not specific to a particular
module or subsystem.
Obx This directory contains the Obx subsystem, a collection of examples.
Std This directory contains a number of command packages available to the user.
System This directory contains the core of Oberon/F.
Text This directory contains the Text subsystem, with the standard
document/program editor.
Installation of Release 1.2 over Release 1.1
Rename the old Oberon directory, install the new one as outlined above, and then move over the old Mod directory and any subsystem directories that you may have created. Finally, update the System/Rsrc/Menus file in the new version with the menu entries that you may have added or changed.
To learn about how to migrate your sources and documents from Release 1.1 to Release 1.2, consult the document
Manuals/Changes
Deinstallation
Simply delete the whole Oberon directory.
Document Windows, Tool Windows, Auxiliary Windows
There are three kinds of windows in Oberon/F: document windows, tool windows, and auxiliary windows.
A document window may contain e.g. a text or a form layout, or your custom view object type. When the contents of a document window have been modified (made "dirty") and the user tries to close the window (or quit the application), the system asks whether it should save the document.
A tool window allows to invoke actions on some document window underneath it. Typically, tool windows are used for modeless dialogs.
Windows:
Tool windows look the same way as dialogs.
Mac OS:
Tool windows look the same way as modeless dialogs, i.e. the same way as a document. In order to make it possible for the user to distinguish tool and document windows, titles of tool windows are put between "<<" and ">>" brackets.
Auxiliary windows are used mainly to hold temporary data for information purposes, e.g. the output of a browser. The contents of an auxiliary window may be editable, but the system does not ask whether a modified auxiliary window should be stored, i.e. it is temporary in nature. The Log window is an example of an auxiliary window.
Windows:
On Windows 3.1, there is no visible difference between document and auxiliary windows. On Windows 95, a document window is decorated with the Oberon/F document icon, while an auxiliary window is decorated with the Oberon/F application icon. A tool window is not decorated with an icon.
Mac OS:
Auxiliary windows look the same way as any document. In order to make it possible for the user to distinguish auxiliary and document windows, the titles of auxiliary windows are put between "[" and "]" brackets.
Document Size
The size of a document, or more exactly of its outermost ("root") view, can be updated in several ways. Its width, or independently its height, can be bound either to a fixed size, to the paper as defined in the Page
Setup dialog, or to the window's current size.
For example, text views by default have a width bound to the page size, and a height bound to the window size. Documentation is often bound to the current window size in both dimensions. Such bindings can be changed with the Tools->Document Size... dialog.
Menu Configuration
The configurable menus can be inspected using Info->Menus. The displayed text can be edited, and the current menu configuration updated accordingly (Info->Update
Menus). To make changes to the menus permanent, the menu text must be saved to disk. The file System/Rsrc/Menus contains the startup menu configuration, i.e. the text which is opened when Info->Menus is executed.
The menu text consists of a sequence of menu definitions, which themselves consist of sequences of menu items. An example is the following extract of a possible Dev menu definition:
Each menu has a name, in this case it is Dev. Optionally, the menu name can be followed by a menu type, e.g.
MENU "Text" ("TextViews.ViewDesc")
A typed menu is only installed in the menu bar as long as the current focus has a matching type, i.e. it is context-sensitive. The other menus are always available.
Mac OS:
Standard menus, i.e. File, Edit, Font, Attributes, and Windows are predefined and not part of a menu configuration text.
There are two kinds of menu items: normal items and separators. A separator optically organizes a menu into different groups of items. Normal menu items consist of four strings: a name, a keyboard equivalent, an action command, and a guard command. The name is the string presented to the user in the menu. A "&" character indicates which character of the name should be underlined (this is a Windows feature, and not available on Mac OS). If you want a "&" to appear, you should write a "&&" (this also holds for the Mac OS, i.e. the syntax is the same for both platforms).
The keyboard equivalent, which may be empty, allows to associate a key to the menu item. The action string contains the command sequence which is activated when the menu item is executed. The guard string, which may be empty, contains a command which is called to determine whether the item is currently enabled or disabled, checked or unchecked, or to set up a current item name which overrides the normal name (e.g. to toggle between Show
XYZ and Hide
XYZ).
Note: the menu guard is executed e.g. when the user clicks in the menu bar. This causes the guard's module to become loaded, even if the user never uses the corresponding command.
Note: the menu guard is evaluated only once. If the guard's module cannot be loaded, the menu item remains disabled and the guard is not executed again (for performance reasons). If the module's code becomes available later, e.g. because its module was later compiled, the menu item will remain disabled. To force a re-evaluation of the guard, use the Dev->Flush
Resources command.
Windows:
The following keyboard shortcuts can be specified in the keyboard equivalent string:
"A".."Z", "0".."9" modifier + key
"*A".."*Z", "*0".."*9" shift + modifier + key
"F1".."F12" function key
"^F1".."^F12" modifier + function key
"*F1".."*F12" shift + function key
"*^F1".."*^F12" shift + modifier + function key
See also modules
StdMenuTool
and
StdCmds
String Resources
String resources are files which define a mapping between strings, e.g. the string "untitled" may be mapped to "sans titre". This is useful to prevent hard-wiring textual messages in the program code, in order to make later editing of these messages possible without requiring a recompilation. From a programming point of view, string translation is done in several procedures of module Dialog, e.g. Dialog.MapString. String resource files can be normal Oberon/F text documents, which simply consist of the keyword STRINGS followed by a sequence of lines; each line contains a string (the key), a TAB, another string (to which the key is mapped), and a carriage return, e.g.
STRINGS
untitled sans titre
open ouvre
close ferme
There can be one string resource file per subsystem (->Subsystems and Global Modules). For example, a call of
in a program maps the string "CntrlInstallFailed" according to the table in the Form/Rsrc/Strings file. In the English version, the mapping is "form controller installation failed". In a German version, "CntrlInstallFailed" might be mapped to "Der Form Controller konnte nicht installiert werden".
Standard Commands
In this section, the menu items of the standard menus File, Edit, Font (Mac OS), Attributes, and Window(s) are described. For a menu item which is not permanently enabled, the condition for enabling it is specified. Often, such a guard command is one of the commands exported by module StdCmds.
Windows:
Under Windows, the standard menu items can be configured in the same way as all other menu items, by editing the System/Rsrc/Menus document. Most standard menu items are calls to a command exported by module StdCmds.
File Menu
Opens a new document window containing an empty text view.
Open...
Opens the standard file Open dialog.
Mac OS:
Only Oberon/F documents (i.e. Mac OS files with file type = "oODC"), directories, and volumes are shown. By clicking the more
files check box, all other files for which there are converters are shown as well. In the format pop-up menu, a converter can be chosen in case there are several possible importers.
Close
Guard: front window
Closes the front window. If the window is a primary document window and its contents has been modified ("dirty"), the user is asked whether to save the window's contents in a file.
Guard: dirty front document window
Saves the front window's contents to a file. If the window's contents has not yet been saved to a file, the user is asked for a file name.
Save As
Guard: front window
Saves the front window's contents to a file. The user is always asked for a file name.
Page Setup...
Guard: front window
Asks the user for the page information of the front window's document, for later printing.
In addition to the data which is specific to the current printer driver, the margins can be set (the distances between the paper's edges and the printed area), and a standard header can be switched on or off. The standard header consists of a page number and a date.
Mac OS:
When using LaserWriter 7.x.y drivers, you should switch on greyscale printing (not black/white), otherwise printing may produce entirely black pages. If possible, switch to LaserWriter 8.x.y drivers, which don't show this behavior.
Print...
Guard: front window
Asks the user for printing information, and then creates a print-out accordingly.
Exit (Windows)
Quit (Mac OS)
Terminates the application. If windows with modified contents are open, the user is asked whether to save them in files.
Edit Menu
Undo [...]
Guard: non-empty undo stack of operations
Reverses the effect of the most recent modifying operation. Usually, the kind of operation is given behind the word "Undo", e.g. Undo
Paste. Undo can be activated several times, until the opening, creation, or most recent saving of the document. Under low-memory conditions, the number of undoable operations may become reduced.
Redo [...]
Guard: non-empty redo stack of operations
Restores the effect of the most recently undone operation. Usually, the kind of operation is given behind the word "Redo", e.g. Redo
Paste.
Guard: selection in focus view in front window
Deletes the selection and puts a copy into the clipboard.
Guard: selection in focus view in front window
Puts a copy of the selection into the clipboard.
Paste
Guard: caret in focus view in front window, non-empty clipboard
Pastes a copy of the clipboard's contents at the caret position. If the focus view contains the same kind of data as the clipboard, the data is inserted directly into the focus view's data. Otherwise, and if the focus view is a container, a copy of the whole view containing the clipboard data is inserted into the focus view's data.
Delete (Windows)
Guard: selection in focus in front window
Deletes the selection, without putting it into the clipboard.
Paste Object (Windows)
Paste as Component (Mac OS)
Guard: caret in focus view in front window, non-empty clipboard
Pastes a copy of the clipboard's contents at the caret position. If the focus view is a container, a copy of the whole view containing the clipboard data is inserted into the focus view's data.
Paste to Window (Windows)
Guard: non-empty clipboard
Opens a copy of the clipboard's contents into a new document window.
Object Properties... (Windows)
Opens an appropriate property sheet for the selected view.
Object (Windows)
Guard: a selected view
Shows a submenu with commands for the selected view:
Edit
Makes the selected view the current focus view.
Open
Opens a new window showing a second view to the selected object.
+ verbs defined for the selected view.
Clear
Guard: selection in focus view in front window
Deletes the selection, without putting it into the clipboard.
Select Document
Guard: front window
Selects the root view of the front window's document as a singleton. Note the difference to Select
All, which selects the latter's contents instead (or rather the contents of whatever view is currently the focus).
Select All
Guard: selectable focus view in front window
Selects the whole focus view's contents.
Select Next Object (Windows)
Guard: focused view is a container
If a view in the container is selected: select the next view.
If the last view is selected or there is no singleton selection: select the first view.
Component Info (Mac OS)
Guard: singleton selection
Opens a modeless dialog with some information about the selected view.
View In Window (Mac OS)
Guard: front window
Opens a new window on the front window's focus view. If the window is already open, it is brought to the top. The window's title is put between "(" and ")" parentheses.
Font Menu (Mac OS)
Available: font-carrying selection or caret in focus view in front window
This menu lists all the fonts which are currently available. The menu item for the caret's font, or the font of the selection if it is homogeneous, is checked.
Attributes Menu
Available: style/size/color-carrying selection or caret in focus view in front window
The following commands work on the selection; if there is no selection, the caret's current attributes are affected instead. These attributes are used as defaults when typing in new text.
For colors, there is a system-wide color (default color) which can be modified by the user. Everything drawn in this color will be updated accordingly.
Regular (Windows)
Plain (Mac OS)
Guard: style-carrying selection or caret in focus view in front window
Checked: if text to the left and to the right of the caret is plain, or if selection is homogeneously plain (i.e. non-bold, non-italicized, non-underlined, and non-striked-out).
Removes all style attributes (bold, italic, underline, strikeout) from the selection.
Guard: style-carrying selection or caret in focus view in front window
Checked: if text to the left and to the right of the caret is bold, or if selection is homogeneously bold.
If the selection is homogeneously bold, it is made non-bold, otherwise it is made bold.
Italic
Guard: style-carrying selection or caret in focus view in front window
Checked: if text to the left and to the right of the caret is italic, or if selection is homogeneously italic.
If the selection is homogeneously italic, it is made non-italic, otherwise it is made italic.
Underline
Guard: style-carrying selection or caret in focus view in front window
Checked: if text to the left and to the right of the caret is underlined, or if selection is homogeneously underlined.
If the selection is homogeneously underlined, it is made non-underlined, otherwise it is made underlined.
Strikeout (Mac OS)
Guard: style-carrying selection or caret in focus view in front window
Checked: if text to the left and to the right of the caret is striked out, or if selection is homogeneously striked out.
If the selection is homogeneously striked out, it is made non-striked-out, otherwise it is made striked out.
9 point, 10, 12, 16, 20, 24
Guard: size-carrying selection or caret in focus view in front window
Checked: if text to the left and to the right of the caret has the given size, or if the selection is homogeneously of the given size.
The selection is set to the given point size.
Size... (Windows)
Other Size... (Mac OS)
Guard: size-carrying selection or caret in focus view in front window
Checked: if none of the other sizes apply
A tool dialog is opened, which allows to enter a particular font size in points, and then to set the selection to this size.
Default Color
Guard: color-carrying selection or caret in focus view in front window
Checked: if text to the left and to the right of the caret has the default color, or if the selection is homogeneously of the default color
Sets the selection's color to the default color.
Black
Guard: color-carrying selection or caret in focus view in front window
Checked: if text to the left and to the right of the caret is black, or if the selection is homogeneously black
Sets the selection's color to black.
Guard: color-carrying selection or caret in focus view in front window
Checked: if text to the left and to the right of the caret is red, or if the selection is homogeneously red
Sets the selection's color to red.
Green
Guard: color-carrying selection or caret in focus view in front window
Checked: if text to the left and to the right of the caret is green, or if the selection is homogeneously green
Sets the selection's color to green.
Guard: color-carrying selection or caret in focus view in front window
Checked: if text to the left and to the right of the caret is blue, or if the selection is homogeneously blue
Sets the selection's color to blue.
Color... (Windows)
Other Color... (Mac OS)
Guard: color-carrying selection or caret in focus view in front window
Checked: if none of the other colors apply
Asks the user for a color, to which it then sets the selection.
Set Default Color... (Mac OS)
Guard: color-carrying selection or caret in focus view in front window
Asks the user for a color, to which it then sets the default color.
Font... (Windows)
Guard: font-carrying selection or caret in focus view in front window
Opens the standard font dialog and applies the chosen font attributes to the selection.
Typeface... (Windows)
Guard: font-carrying selection or caret in focus view in front window
Opens the standard font dialog and applies the chosen font attributes to the selection. In contrast to the Font... command, only the typeface (the name of the font) is changed, but not the other attributes like size or weight (bold/normal).
Window Menu (Windows)
Windows Menu (Mac OS)
New Window (Windows)
Guard: front window
Opens a new window on the same document as the front window. The window is of the same kind as the front window. The window's title is put between "(" and ")" parentheses.
Cascade (Windows)
Stack (Mac OS)
Guard: front window
Arrange document windows in an overlapping fashion.
Tile Horizontal
Arrange windows from left to right in a non-overlapping fashion. This command does not affect non-resizable windows, and it ignores some windows when there are too many open windows for a reasonable tiling. The front window becomes the left-most window.
Tile Vertical
Arrange windows from top to bottom in a non-overlapping fashion. This command does not affect non-resizable windows, and it ignores some windows when there are too many open windows for a reasonable tiling. The front window becomes the top-most window.
Arrange Icons (Windows)
Arrange icons (minimized windows) at the bottom of the application window.
Show Clipboard / Hide Clipboard (Mac OS)
If the clipboard is open, it closes it and all its secondary windows. Otherwise it opens a clipboard window.
windows (Mac OS)
Here the list of open windows is appended, the front window at the top (checked). Document window titles are in boldface if their contents has been modified.
(.txt)